AI 擅長讀取現有程式碼、設定檔、API 文件與系統說明，也能快速整理出系統目前的樣貌。它取得的資訊多半集中在「現在長什麼樣」，若想知道當初為何做成這樣，就需要靠架構決策紀錄（Architecture Decision Records, ADR）補上。
某個服務為什麼沒有拆出去、某個資料表為什麼沒有正規化、某個流程為什麼保留同步呼叫，背後都有當時的取捨和限制。原因可能是資料遷移風險太高、團隊人力不足，或當時的業務壓力要求先採用較穩定的做法，這些背景不會自然留在程式碼裡。
團隊若只留下最後結果，AI 在協助分析時，就容易根據表面結構做出判斷。它可能看到同步呼叫就建議改成事件驅動，看到單體系統就建議拆成微服務，看到重複程式碼就建議抽成共用模組。這些建議可能當初都已經評估過了，也因為某些不可行的原因才形成當前的結構。
架構決策紀錄的作用，是把當初「為什麼這樣選」留下來。當 AI 或開發者日後重新閱讀系統時，才能同時理解設計結果、限制條件、風險與取捨，避免只根據現有結構重新做一次已經討論過的決策。
架構決策的背景消失後，團隊容易反覆重新討論已經處理過的問題。新人接手系統時，看到某段設計不夠直覺，可能會想把結構整理得更乾淨。那段設計被保留下來，可能是為了避開外部系統限制，也可能是為了配合既有客戶的資料格式。
缺少背景資料時，團隊只能根據現有程式碼推測過去的決策原因。這種推測方式無法涵蓋完整情境，也可能把當年的限制視為設計失誤。
舊問題很少在修改完成後立刻出現。團隊可能先完成重構，測試結果也符合預期，直到系統遇到特殊資料、舊客戶流程、跨系統批次或尖峰流量，才發現被移除的設計是為了處理特定條件。
系統接手困難，除了程式碼複雜，也和決策脈絡中斷有關。新加入的開發者可以透過程式碼理解功能如何運作，仍難分辨哪些地方是刻意設計、哪些地方是暫時妥協，以及哪些問題可以列入後續調整方向。
架構決策紀錄能用輕量方式保存這些資訊。它不需要寫成厚重文件，也不必記錄每一次小幅修改。只要是會影響系統方向、資料邊界、部署方式、技術選型、團隊協作與長期維護成本的決策，就應納入架構決策紀錄的內容。
對接手者來說，一份清楚的架構決策紀錄可以降低理解成本。開發者修改模組前，可以先了解當初如何劃分邊界、評估過哪些替代方案，以及最後接受了哪些代價。程式碼審查也能聚焦在原有條件是否已經改變，以及新的方案是否適合目前情境。
AI 輔助開發也需要這些背景。團隊把相關架構決策紀錄放入 AI 的上下文後，AI 才能同時參考程式碼結構與過去留下的工程判斷，提出較貼近現況的修改方向。
架構決策紀錄最先需要寫清楚的是當時的背景。「系統需要擴充」或「效能需要改善」這類描述太薄，接手者還需要知道團隊當時為什麼需要做出這項決策、面對哪些限制，以及哪些條件讓這件事變得重要。
背景可以包含業務壓力、技術限制、組織條件與時間因素。例如，某個模組選擇先保留在單體系統中，可能是因為當時交易流程仍未穩定，資料邊界也尚未釐清。某個系統選擇沿用既有資料庫，可能是因為維運團隊已經熟悉相關的備份、監控與權限管理。
這些條件若沒有被記錄，接手者只能看到設計結果，很難理解當時的判斷依據。
AI 輔助開發時，背景資料也會影響建議品質。架構決策紀錄若只寫下「採用某項方案」，AI 就無法判斷哪些條件不能改動。
例如，團隊可以在架構決策紀錄中註明：「目前不能更動既有資料格式，因為外部系統每天晚上會進行批次匯入。」後續請 AI 協助重構時，它才能避開不符合現況的修改方向。
架構決策紀錄第二個需要寫清楚的是最後採用的決策。這段內容要直接說明團隊選擇了什麼做法、適用範圍到哪裡，以及會影響哪些系統、模組或團隊。
篇幅不必太長，內容需要具體，避免只留下「改善架構」、「導入事件機制」或「重構會員模組」這類難以確認實際做法的結論。
決策應寫成可被檢查的描述。例如：「訂單成立後，由訂單服務發布訂單建立事件，庫存服務與通知服務各自訂閱，訂單服務不再直接呼叫這兩個服務。」這段記錄能清楚呈現系統互動方式的改變，也說明團隊希望降低訂單服務對下游服務的直接依賴。
架構決策紀錄也可以簡要記錄曾經評估的替代方案，內容只要說明團隊考慮過哪些路線，以及未採用的原因，不用寫成長篇大論的完整研究報告。
當 AI 再次提出過去已評估的方案時，團隊可以透過架構決策紀錄回顧當時的判斷。例如，紀錄中若寫明「曾評估拆分為獨立服務，因資料一致性風險過高而未採用」，後續討論便能直接確認這項風險是否已經降低。
決策內容也要標明適用範圍。某項方案可能只適用於單一子系統，不能直接延伸成整個組織的共同規範。範圍記錄得夠清楚，團隊日後引用這項決策時，才能判斷原有條件是否成立，避免把局部做法套用到其他情境。
架構決策紀錄最容易被省略的部分，是決策帶來的後果與取捨。
每項設計決策都會帶來一些好處，也會增加新的成本與責任。這些代價若沒有被記錄，後續接手的人可能只看見方案的優點。等到問題出現時，也很難理解團隊當初為什麼接受這項選擇。
例如，採用事件驅動可以降低服務之間的直接依賴，同時需要處理訊息追蹤、失敗重送、事件順序與資料一致性。維持單體系統可以控制部署與除錯的複雜度，團隊也需要更嚴格地管理模組邊界。使用共用函式庫可以減少重複程式碼，版本升級與相依關係則需要更謹慎地維護。
記錄後果與取捨，可以讓團隊完整理解這項決策。內容不需要證明當初的選擇正確，重點是說明團隊接受了哪些代價，以及哪些風險需要關注。當系統規模、團隊能力、流量條件或業務規則改變時，團隊便能重新檢查原有取捨是否仍符合目前情境。
AI 輔助分析也需要這些資訊。架構決策紀錄保存已知代價後，AI 才能針對現有問題提出具體改善方向。例如，團隊已經確認事件追蹤困難，就可以要求 AI 協助補上追蹤識別碼、日誌規範、重送機制與測試案例，避免討論再次回到更換架構風格。
重構常從一個合理的直覺開始：這段程式太亂、這個模組太大、這個流程太難測，或這個相依關係太複雜。
AI 加入開發流程後，這些判斷能更快轉成具體行動。開發者可以請 AI 分析程式碼，也能迅速產生新的結構與重構草稿。產出速度提高後，動手前更需要先確認原始設計理由。
架構決策紀錄可以幫助團隊在動手前理解原始設計理由。某個模組看起來過大，可能是因為交易資料必須在同一個交易邊界內完成。某個資料模型看起來不夠整齊，可能是為了相容舊系統的匯入格式。某個流程尚未拆分，可能是因為營運團隊當時無法維護多個部署單元。
這些理由提供了重構前的判斷基準。團隊可以先確認當年的限制是否仍然存在、原先接受的代價是否已經超出可接受範圍，以及現在是否具備新的技術、測試、平台或團隊能力來承接新的設計。
這項基準也能降低草率重構的風險。AI 容易根據程式碼結構判斷哪些地方需要整理，對業務規則與系統邊界造成的複雜度則需要額外背景。架構決策紀錄補上這些資訊後，重構就能建立在現況條件之上，減少只為了讓程式碼看起來整齊而進行的修改。
AI 協助進行架構分析時，輸入的上下文會直接影響輸出品質。若只提供程式碼、資料表與 API 文件，AI 多半會依照一般設計原則提出建議，例如降低耦合、拆分服務、抽出共用邏輯、加入事件機制，或調整資料模型。
這些方向可以參考，卻不一定符合即有限制，採用前仍要檢查系統邊界、資料限制與團隊能力。
架構決策紀錄可以成為 AI 分析時的重要上下文來源。團隊把相關架構決策紀錄一併提供給 AI 後，AI 就能讀到採用方案、未採用選項，以及團隊已知的後果與取捨。這些資訊能減少過去已經評估過、現階段仍不適合的建議。
團隊可以透過專案設定檔（如 .cursorrules 或 CLAUDE.md）要求 AI 在重構前先讀取架構決策紀錄，或是整合檢索增強生成（Retrieval-Augmented Generation, RAG）來精準餵給 AI 相關決策紀錄，避免受到上下文長度限制或舊決策的干擾。
例如，團隊請 AI 評估「是否要把訂單模組拆成獨立服務」時，若架構決策紀錄已經記錄當初保留在單體系統中的原因，包括訂單、付款與庫存共用同一個交易流程，以及測試環境無法穩定模擬分散式失敗情境，AI 的分析就可以聚焦在目前條件是否已經成熟，並且協助檢查測試能力、資料一致性策略、部署流程與監控條件，避免直接產生拆分後的程式碼。
這種做法也能讓 AI 的分析便於審查。審查者可以直接對照架構決策紀錄，確認 AI 是否忽略交易邊界、測試限制或部署條件。
架構討論容易出現各說各話的情況。有人重視效能，有人關注維護性，有人希望加快上線，也有人在意團隊是否有能力接手。
這些角度都有合理性。缺少共同基準時，討論容易停留在個人偏好與過往經驗。架構決策紀錄可以保存過去的決策基準，讓後續討論有清楚的起點。
這個起點包含當時的背景、決策、取捨與後果。團隊準備調整架構時，可以先回到架構決策紀錄檢查幾項條件：當年的限制是否仍然存在、相關風險是否已經降低，以及原先接受的取捨是否仍符合目前規模。討論因此能聚焦在具體條件，減少由個人偏好主導方向的情況。
對跨角色協作而言，架構決策紀錄也能幫助產品、工程、維運與管理者理解同一份決策脈絡。產品端可以知道某些需求為什麼修改成本較高，維運端可以理解部署限制的來源，管理者也能看見技術改善前需要補上的測試、監控或平台能力。
架構決策紀錄（Architecture Decision Records, ADR）要能發揮作用，需要靠近實際變更，因此要讓架構決策紀錄跟重要的程式碼變更一起出現。
為了減少團隊維護架構決策紀錄的負擔，可以先定義決策門檻，明確判斷哪些變更需要留下紀錄。當拉取請求（Pull Request，PR）涉及系統邊界、資料模型、服務互動、部署方式、技術選型或長期維護成本時，團隊應要求附上一份簡短的架構決策紀錄。
這樣能讓架構討論貼近實際變更。開發者提出拉取請求時，除了說明修改了哪些檔案，也要交代這項選擇背後的原因。審查者在檢查拉取請求時，也能進一步確認這項決策是否符合系統方向、是否忽略既有限制，以及是否會增加後續維護壓力。
團隊可以把它一同放在程式碼儲存庫（Repository）的指定目錄中，並以 Markdown 檔案保存。拉取請求描述只要連結相關架構決策紀錄，後續查詢時就能從程式碼變更回到決策背景。AI 分析某段程式碼時，也能沿著同一個連結找到當初的判斷。
當這項決定會影響後續多次修改，就適合要求做成架構決策紀錄。例如導入新的訊息佇列、調整服務拆分方式、改變認證機制、選擇新的資料儲存方式，或決定某個模組暫時不拆分。這些內容若只留在會議紀錄或聊天訊息中，幾個月後就很難被重新找到。
架構決策紀錄保留的是決策，而決策會隨系統環境改變。
某項決策在當時合理，三年後可能已經不符合新的條件。團隊若只把架構決策紀錄當成靜態文件，時間久了同樣會面臨內容失效。
因此，架構決策紀錄需要搭配簡單的狀態管理，才能讓讀者知道這份決策目前是否仍能作為設計依據。
常見狀態可以維持精簡，例如提議中、已採用、已取代與已廢止。提議中的架構決策紀錄表示團隊仍在討論，尚未形成正式方向。已採用表示這是目前有效的決策。已取代表示後續已有新的架構決策紀錄接手，原文件則保留歷史脈絡。已廢止表示當初的限制已經消失，或原有方向已不符合目前需求。
狀態管理可以幫助後續團隊正確使用文件。開發者看到已採用的架構決策紀錄，可以將它視為目前的設計依據。看到已取代的架構決策紀錄，可以沿著連結找到新的決策。看到已廢止的架構決策紀錄，也能理解團隊曾經採用過哪些做法，以及後來調整方向的原因。
架構決策紀錄的狀態也會影響 AI 取得的上下文。團隊若把所有架構決策紀錄直接提供給 AI，AI 可能把舊決策誤認為目前規則。透過狀態管理，團隊可以明確指定 AI 應參考哪些架構決策紀錄，並排除已經不適用的內容。
架構決策紀錄要進入日常流程，格式就不能過重。文件一旦需要填寫過多欄位、經過多層審核，或寫得像正式報告，團隊很快就會把它視為額外負擔。讓架構決策紀錄保持短小、清楚，並能在短時間內讀完。
一份架構決策紀錄多半只需要說明幾件事：當時的背景、最後採用的決策、評估過的替代方案、接受的後果與取捨，以及目前狀態。
這些內容不需要寫成長篇分析，只要足以讓後續接手的人理解當時的判斷即可。對多數團隊來說，一到兩頁的 Markdown 已經足夠。
輕量格式仍然要保留關鍵脈絡。像「採用 Kafka」這類紀錄只保留了結果，能提供的幫助有限。完整的寫法還需要說明為什麼需要事件串流、為什麼選擇 Kafka、當時放棄了哪些方案，以及團隊接受了哪些維運與觀測成本。
架構決策紀錄與重要拉取請求建立連結、具備清楚狀態，並維持輕量格式後，才有機會進入日常開發。這樣團隊使用 AI 分析系統、產生修改建議或進行重構時，才能把過去的工程判斷帶進新的工作流程。
# ADR-007：付款模組拆分為獨立服務
## 狀態（Status）
Accepted
## 建立日期（Date）
2026-05-25
## 參與決策者（Deciders）
王小明、方大同、李不悅
## 背景（Context）
目前單體系統（Monolith）的部署時間開始增加。付款功能流量成長後，也開始影響其他模組穩定性。
每次修改付款流程時，整體系統都需要一起部署，導致交付風險慢慢提高。
## 決策（Decision）
團隊決定先將付款模組拆分為獨立服務，其餘功能仍維持單體架構。
## 替代方案（Alternatives）
目前暫不全面拆分微服務（Micro-services），避免一次增加過多部署與維運複雜度。
## 取捨（Trade-off）
拆分付款服務後，團隊可以獨立部署付款流程，也能單獨擴展高流量服務。
服務拆分後，跨服務溝通、監控、API 相依性與錯誤追蹤複雜度也會提高。
團隊目前接受這些額外維運成本，優先改善付款功能影響整體系統穩定性的問題。
## 後續影響（Consequences）
後續需要補強系統可觀測性（Observability）、API 監控（Monitoring）與分散式追蹤（Distributed Tracing）能力。
未來若更多模組開始拆分，團隊也需要重新評估服務治理與部署流程。
iThome鐵人賽
看影片追技術